---

11. Debugging Source Code

This chapter describes the CodeWarrior source-level debugger. To a great extent, this debugger works for all supported chips, operating systems, and languages (C, C++, Pascal, Java, and assembly language).

A debugger controls program execution so that you can see what happens internally as your program runs. You use a debugger to find problems in your program's execution. The debugger can execute your program one statement at a time, suspend execution when control reaches a specified point, or interrupt the program when it changes the value of a designated memory location. When the debugger stops a program, you can view the chain of function calls, examine and change the values of variables, and inspect the contents of the processor's registers.

The other topics in this chapter are:

• Symbolics Files
• Preparing for Debugging
• Using the Debugger
• Guided Tour of the Debugger
• Basic Debugging
• Expressions
• Troubleshooting

A project's symbolics file contains information the debugger needs to debug the project, such as the names of routines and variables (the symbols), their locations within the source code, and their locations within the object code.

The debugger uses the symbolics file to display the source code that corresponds to your object code. For example, when you stop a program's execution to examine it, the debugger shows you the source code.

You can also view the corresponding assembly-language instructions and memory addresses. See "Viewing source code as assembly" on page 402 for more information.

CodeWarrior supports several different symbolics formats appropriate for a variety of build targets. Table 11.1 lists some of the supported formats:

Format	Principal Build Target
CodeView	Win32
DWARF	Embedded systems
SYM	Mac OS

See "Preparing for Debugging" on page 390 for information on how to set up projects and source files to create symbolics files.

For more information on compiler and linker settings, refer to "Configuring Target Options" on page 315.

To learn more about symbolics files for a particular build target, see the corresponding Targeting manual.

To debug the code generated by a particular build target within your CodeWarrior project file, both the build target and the individual source files within it must be configured for debugging. After the build target and source files are configured properly, CodeWarrior generates symbolics information for use by the debugger.

This section discusses the following topics:

• Setting Up a Build Target for Debugging
• Setting Up a File for Debugging
• Generating Symbolics Information

To prepare a build target for debugging, make sure it is the active build target. Then, choose the Enable Debugger command from the Project menu. When debugging is enabled for a build target, the menu command changes to Disable Debugger. Choosing Disable Debugger turns off debugging for the build target and changes the menu command back to Enable Debugger.

The Enable Debugger command activates the debugger. When your project's target settings are correctly configured, the compiler and linker generate a symbolics file containing information for debugging at the source-code level. By default, this symbolics file is saved in the same location as the output directory.

See "Configuring Target Options" on page 315 for more information on build target settings.

When you choose Enable Debugger, you might see an alert (Figure 11.1). CodeWarrior is reminding you that it will modify the build target settings to prepare the project for debugging. Click Yes to apply the debugging changes to your build target.

After you enable debugging for the current build target, you have to set up your individual files for debugging. If you intend to debug your program, you typically enable debugging for all of your source files.

The Project window includes a debug column, as shown in Figure 11.2. For files, a mark in this column means that symbolic information is generated; no mark means that symbolic information is not generated. For group names, a mark indicates that debugging is enabled for every file in the group and no mark means that debugging is disabled for one or more files in the group.

To toggle debugging for a file, click in the Debug column for that file. Clicking in the Debug column for a group name enables or disables debugging for all files in that group. If a file cannot be debugged (because it is a library or other non-source file), you cannot enable debugging for that file.

To generate symbolics information, both the current build target and the source files within that target must be prepared for debugging. See Setting Up a File for Debugging to learn how to do this.

After you prepare the current build target and its source files, choose the Make command from the Project menu to compile and link your final code.

For more information on compiling and linking, see "Configuring Target Options" on page 315 as well as the Targeting manual for your particular platform target.

To debug a project, you must first enable debugging for that project. Choose Enable Debugger from the Project menu to enable debugging. After debugging is enabled, the Enable Debugger command changes to Disable Debugger.

When you enable debugging, the Run command in the Project menu changes to Debug. The Debug command compiles and links your project, generates a symbolics file, and activates the debugger. The debugger automatically loads the symbolics file so that you can debug your project. See "Preparing for Debugging" on page 390 for more information on this topic.

There are many build targets or kinds of code that the IDE cannot launch. For example, if you are writing an application plug-in, the plug-in cannot run on its own. In addition, the CodeWarrior IDE does not know which application must be running to invoke the plug-in. In such cases, you would need to specify the application that must launch in order to invoke the plug-in.

Usually, you open the symbolics file to debug the plug-in. Alternatively, you can follow these steps:

1. Open the Target Settings window for the project.

Choose Target Settings from the Project menu, where Target is the name of the current build target. For example, if your current build target is named MyAppRelease, you would choose MyAppRelease Settings from the Project menu.

2. Display the Runtime Settings panel.

Scroll through the list of panels on the left side of the Target Settings window. Click Runtime Settings to display that panel on the right side of the window.

3. Click the Choose button.

The IDE displays a dialog box to help you choose an application to launch when debugging shared libraries, dynamic link libraries (DLLs), and code resources. The IDE launches the application you specify when debugging the plug-in.

This section explains the various windows, panes, and displays you can use when debugging. The topics discussed in this section include:

• Stack Crawl Window
• Source Code Browser Window
• Auto-Variables View
• Debugger Contextual Menu
• Expressions Window
• Global Variables Window
• Breakpoints Window
• Watchpoints Window
• Log Window
• Variable Window
• Array Window
• Memory Window
• Register Windows
• Processes Window

When the debugger opens a symbolics file, it opens a Stack Crawl window (formerly known as the Program window). This window is shown in Figure 11.3. The debugger allows more than one symbolics file to be open at a time: that is, you can debug more than one program at a time. For example, you can use this feature to debug an application and separate plug-ins for the application. A Stack Crawl is displayed for each active symbolics file and each thread.

The Stack Crawl window displays debugging information about the currently running routine. The Stack Crawl window has four points of interest:

• Debugger toolbar
• Stack Crawl pane
• Variables pane
• Source pane

The active pane has a heavy border.

To select items in a focused Stack Crawl pane or Variables pane, type the first few characters of the item's name. You can also use the arrow keys to navigate through the items in an active pane.

You can also use Control-Tab as another way to navigate through items in an active Stack Crawl pane or Variables pane. To learn more about customizing key bindings, see "Customizing Key Bindings" on page 297.

There are additional controls along the very bottom of the Source pane, to the left of the horizontal scroll bar:

• the Routine Pop-Up Menu
• the Line Number Button
• the Source pane pop-up menu

Figure 11.3 Parts of the Stack Crawl window

The debugger toolbar (Figure 11.4) contains shortcut buttons for commonly used commands from the Project and Debug menus: Run, Stop, Kill, Step Over, Step Into, and Step Out.

Choose Window > Toolbar > Show Window Toolbar to display the toolbar. To hide the toolbar, choose Window > Toolbar >
Hide Window Toolbar.

For more information, see "Basic Debugging" on page 427.

The Stack Crawl window includes a Stack Crawl pane. This pane displays the current subroutine calling chain (Figure 11.5). Each subroutine is placed below the routine that called it. Select any routine in the Stack Crawl pane to display its code in the Source pane.

Figure 11.5 Stack Crawl pane

The Variables pane displays a list of local variables used in the program. The listing of these variables is controlled by the Variables Pane Listing icon (), shown in Figure 11.6. Clicking this icon toggles the list in the Variables pane between Variables:All and
Variables:Auto. These two list types are described in Table 11.2.

Type	Variables Listed
Variables:All	All local variables in the code
Variables:Auto	Local variables of the routine in which the Current-statement arrow is currently located

The Variables pane also displays any global variables referred to by the routine. Local and global variables are separated by a dashed line.

The Variables pane lists the variables in outline form. Click the hierarchical control next to an entry to expand or collapse the view of its contents.

For example, in Figure 11.6, clicking the hierarchical control next to the variable msg hides its members. Click the hierarchical control again to display the members. You can dereference multiple levels of pointers to get directly to the data by pressing the Ctrl/Option key while expanding an entry. This feature is useful for expanding a handle to a structured type and viewing the structure's members.

The Source pane in the Stack Crawl window displays source code. The debugger takes the source code directly from the current build target's source code files, including any comments and white space. The pane shows C/C++, Pascal, Java, and in-line assembly code exactly as it appears in your program's source code (Figure 11.7), using the font and color specified in the IDE's Editor Settings panel.

Click the Source pane disclosure triangle, shown in Figure 11.3 on page 397, to display or hide the Source pan. If you hide the Source pane, the debugger opens both an editor window and a Stack Crawl window the next time you start a debugging session. The editor window displays the same source code and breakpoints as the Source pane.

The Source pane lets you step through the program's source code line by line. Its progress is shown by the current-statement arrow, which always points to the next statement to be executed. The current-statement arrow is sometimes called the program counter.

If there are two or more routine calls on a single line, each routine is executed separately as one step before the current-statement arrow moves to the next line. When this happens, the arrow is dimmed whenever the program counter is within, but not at the beginning of, a source-code line.

Figure 11.8 Source and assembly views

To view your source code as assembly language, click the Source pop-up menu at the bottom of the Stack Crawl window. Choose Assembler to display the contents of the Source pane as assembly code (Figure 11.8). While viewing assembly code, the debugger still lets you step through the code and set breakpoints, one routine at a time.

To view your source code and assembly language together, click the Source pop-up menu at the bottom of the Stack Crawl window. Choose Mixed to display the source code of the current routine intermixed with assembly code (Figure 11.9). The source code that produced the assembly instructions appears before the assembly itself. When viewing code in mixed view, you can set breakpoints and step through code, but only for assembly language instructions. Notice you cannot set breakpoints on source code lines, as shown in Figure 11.9.

If no symbolics information is available for the object code, the display reverts to Assembly. There is no syntax highlighting for this view, so the Source pane displays all text in plain format.

The Function pop-up menu, at the bottom-left corner of the Source pane, contains a list of the routines defined in the source file selected in the Source pane (Figure 11.10). Selecting a routine in the Function pop-up menu displays that routine in the Source pane.

Alt/Option click the Function pop-up menu to display the menu items in alphabetical order.

Figure 11.10 Function pop-up menu

When you double-click a symbolics file, the debugger opens a Source Code Browser window, as shown in Figure 11.11.

The Source Code Browser window somewhat resembles the Stack Crawl window in both appearance and functionality, but displays different information. The Source Code Browser window lets you view any file in the current build target, whereas the Stack Crawl window can only display the file containing a routine selected from the Stack Crawl pane. You can also use the Source Code Browser window to view or edit the values of all of your program's global variables; the Stack Crawl window lets you change only those global variables referenced by active routines in the call chain. For more information about viewing global variables, see "Global Variables Window" on page 412.

For beginners

The Source Code Browser window has three panes:

• Files pane at the top left
• Functions pane at the top right
• Source pane on the bottom

The active pane has a heavy border.

To select items in an active Files pane or Functions pane, type the first few characters of the item's name. You can also use the arrow keys to navigate through the items in an active pane.

You can also use Control-Tab as another way to navigate through items in an active Files pane or Functions pane.

The debugger allows more than one symbolics file to be open at a time: that is, you can debug more than one program at a time. You can use this feature, for example, to debug an application and separate plug-ins for the application. A Source Code Browser window is displayed for each opened symbolics file.

To learn more about the contents of the Stack Crawl window, refer to "Stack Crawl Window" on page 395.

The Files pane in the Source Code Browser window (Figure 11.12) displays a list of all source files associated with the current build target you are debugging. When you select a file name in this pane, the Functions pane displays a list of the routines declared in the file.The Files pane is used in conjunction with the Functions and Source panes to set breakpoints in your program.

For more information, see "Global Variables Window" on page 412 and "Breakpoints" on page 442.

Figure 11.12 Files pane

When you select a source code file in the Source Code Browser window's File pane, the Functions pane (Figure 11.13) presents a list of all routines defined in that file. Clicking a routine name displays that routine in the Source pane at the bottom of the window.

The Source pane in the Source Code Browser window allows you to browse the contents of the source code file selected in the Files pane (Figure 11.14). You can use it to set breakpoints in any file listed in the Files pane. To learn how to set breakpoints, refer to "Breakpoints" on page 442.

Notice, however, that the Source pane does not show the currently executing statement. The current-statement arrow in the Stack Crawl window shows the currently executing statement. You can also use the Stack Crawl window to view local variables. For more information, see "Stack Crawl Window" on page 395.The Source pane displays code in the font and colors specified in the panels of the IDE Preferences window. For more information, see "Editor Settings" on page 269 and "Display Settings" on page 279.

If an item selected in the Files pane does not contain source code, the Source pane displays the message "Source text or disassembly not available."

The bottom of the Source Code Browser window has a Source pop-up menu like the one in the Stack Crawl window (see "Viewing source code as assembly" on page 402). Choose Assembler to display the contents of the source pane as assembly code, as shown earlier in Figure 11.8 on page 402. You can set breakpoints in assembly code, just as you can in source code. Choose Mixed to display source code intermixed with assembly language, as shown earlier in Figure 11.9 on page 403.

The Function pop-up menu, at the bottom-left corner of the Source pane, contains a list of the routines defined in the source file selected in the Files pane. Selecting a routine in the Function pop-up menu displays that routine in the Source pane, just as if you had clicked the same routine in the Functions pane.

Alt/Option click the Function pop-up menu to display the menu sorted alphabetically, as shown earlier in Figure 11.10 on page 404.

When you debug source code, the debugger displays useful information about your program's variables. This information is displayed automatically as you move the cursor over particular variables in source code views. For example, suppose you start a debugging session and examine your source code in the Source pane of the Stack Crawl window. When you position the cursor over the variable i, as shown in Figure 11.15, the debugger displays the current value of that variable.

The debugger includes a contextual menu (Figure 11.16) that provides convenient access to various debugging commands. To display the contextual menu:

Right-click an item.

Control-click an item, or click and hold on an item.

Control-click an item, or click and hold on an item.

The debugger uses the context of the item you select to determine the commands to display in the contextual menu. For example, if you choose a variable, the contextual menu includes commands for viewing the contents of that variable.

The Expressions window (Figure 11.17) provides a single place to put frequently used local variables, global variables, structure members, and array elements without opening and manipulating several windows.

To open the Expressions window, choose Expressions Window from the Window menu.

Use the Copy to Expression command in the Data menu to add selected items to the Expressions window. Alternatively, you can select the same command from the debugger contextual menu (Figure 11.16 on page 411). You can also use the mouse to drag and drop items from other variable panes and windows into the Expressions window. To reorder items in the Expressions window, drag each item to its new position in the list.

Figure 11.17 Expressions window

To remove an item from the Expressions window, select the item and press the Backspace/Delete key. You can also choose Clear from the Edit menu to remove the item.

Unlike local variables displayed in an ordinary Variables window, those in the Expressions window are not removed on exit from the routines in which they are undefined.

To learn about the Expressions window, refer to "Using the Expressions window" on page 461.

The Global Variables window (Figure 11.18) displays all global variables used by your program. You can also view static variables by selecting a file in the File pane. The static variables are displayed in the Variables pane.

To display a global variable in its own window, double-click the variable's name in the Variables pane. A new Variable window opens and displays the variable's name and value. You can also open a Variable window by selecting the desired variable in the Variables pane and selecting the View Variable or View Array commands from the Data menu or the debugger contextual menu (Figure 11.16 on page 411). A global variable displayed in its own window can be viewed and edited the same way as in the Variables pane. You can also add global variables to the Expressions window.

Windows containing global variables remain open for the duration of the debugging session. To close all open Variable windows, make sure that one of the Variable windows is frontmost, then choose Close All Variable Windows from the File menu.

For more information, refer to "Expressions Window" on page 411, "Variable Window" on page 416, and "Array Window" on page 417.

The Breakpoints window (Figure 11.19) lists the breakpoints in your current build target by source file and line number. To open the Breakpoints window, choose Breakpoints Window from the Window menu.

There is a breakpoint marker to the left of each listing. Clicking a breakpoint marker toggles a breakpoint's status. A solid dot indicates that the breakpoint is active, while a circle that indicates that the breakpoint is inactive. In either case, the IDE remembers the position of the breakpoints in the program. Alt/Option click one of the breakpoint markers in the Breakpoints window to simultaneously make all of the listed breakpoints active or inactive. Double-click a breakpoint listing to display the corresponding line of source code in an editor window.

Each breakpoint can have an attached condition. If the condition is true and the breakpoint is active, the breakpoint stops program execution. If the breakpoint is inactive or the condition is false, the breakpoint has no effect.

For more information, see "Breakpoints" on page 442, "Show Breakpoints" on page 620, "Hide Breakpoints" on page 620, and "Conditional breakpoints" on page 446.

The Watchpoints window (Figure 11.20) lists the watchpoints in your current build target by memory address. To open the Watchpoints window, choose Watchpoints Window from the Window menu.

You can clear a watchpoint by selecting it and doing any of the following:

• Choose Clear Watchpoint from the Debug menu.
• Choose Clear from the Edit menu.
• Press the Backspace/Delete key.

The Log window (Figure 11.21) displays messages as your program makes calls to system DLLs or starts new tasks.

To use the Log window, you need to configure your project to display log information. You must enable the Log System Messages preference in the Debugger Settings preference panel. See "Debugger Settings" on page 353 for more information.

You can copy selected text from the Log window with the Copy command in the Edit menu. You can also use the Save As command in the File menu to save the Log window's contents to a text file for later analysis. If you choose to save to a text file, be sure to add an appropriate extension to the file's name, such as ".txt".

The Variable window (Figure 11.22) displays a single variable and allows you to edit its contents. A Variable window containing a local variable will close on exit from the routine in which the variable is defined.

Figure 11.22 Variable window

The Array window (Figure 11.23) displays a contiguous block of memory as an array of elements and allows you to edit the contents of those elements. To open the Array window, select an array variable in a Variables pane (either locals or globals) and then choose View Array from the Data menu.

You can also use the View Memory As command in the Data menu to open an array window. This command presents a dialog box which lets you select a data type, then opens an Array window interpreting memory as an array of that type. For more information, see "View Memory As" on page 623.

The Array window's title bar describes the base address to which the array is bound. An array's base address can be bound to an address, a variable, or a register. Dragging a register name or variable name from a Variables or Registers pane to an Array window sets the array address. An array bound to a local variable will close when the variable's routine returns to its caller.

The Information pane displays the data type of the array elements, along with the array's base address. Clicking the hierarchical control in the Information pane shows more information about the array. From the expanded Information pane, you can select the array's base address, its size, and which members to view if the array elements are of a structured type.

Figure 11.23 Anatomy of an Array window

The array's contents are listed sequentially, starting at element 0. If array elements are cast as structured types, a hierarchical control appears to the left of each array element, allowing you to expand or collapse the element.

The Memory window displays the contents of memory in hexadecimal and corresponding ASCII character values (Figure 11.24). To open a Memory window, select a variable, routine name, or expression representing the desired base address in the Program, Source Code Browser, or Expressions window and choose View Memory from the Data menu.

The source of the base address (which can be a variable, a routine, an expression, or a raw address like 0xCAF64C) is displayed at the top of the window. The Memory window is blank if the IDE cannot access the base address.

To change the base address, simply type a new expression in the Display text field. You can also or drag an expression to the field. If the expression does not produce an object in memory (an lvalue), then the value of the expression is used as the base address. For example, the Memory window expression

will show memory beginning at the address of PlayerRecord.

If the expression's result is an lvalue, then the address of the object is used as the base address. For example, the expression

will show memory beginning at the address of the object pointed to by myArrayPtr.

You can use a Memory window to change the values of individual bytes in memory. Simply click in the displayed data to select a starting point and start typing. If you select a byte in the hexadecimal display, you are restricted to typing hexadecimal digits. If you select a byte in the ASCII display, you can type any alphanumeric character. Certain keys (such as Backspace/Delete, Tab, Enter/Return, and so forth) do not work. New data you type overwrites what is already in memory.

If the expression is a pointer-sized register, then the register's contents are used as the base address. For example, ®A0 (type Option-r for the first character) will show memory beginning at the address contained in the 68K register A0. Note that 64-bit floating-point registers cannot be used on a computer with a 32-bit central processing unit.

A Register window displays register contents and allows you to edit those contents. Different types of Register windows are available for different build targets. Two of the most common Register windows are the General Registers window and the FPU Registers window.

The General Registers window (Figure 11.25) displays CPU registers and allows you to edit register contents. To open a General Registers window, choose Window > Registers Windows > General Registers.

Figure 11.25 General Registers window (Windows)

To change a register's value, double-click the value or select the register and press Enter/Return. You can then type in a new value.

For PowerPC build targets, the General Registers window is shown in Figure 11.26. You can toggle the bit values of the XER and condition registers between 0 and 1. Select the bit you want to change and press Return or Enter. You can also double-click the bit to toggle its value.

Figure 11.26 General Registers window (Mac OS PowerPC)

The FPU Registers window (Figure 11.29) displays FPU registers and allows you to edit register contents. To open an FPU Registers window, choose Window > Registers Windows > FPU Registers.

Figure 11.27 FPU Registers window (Windows)

To change a register's value, double-click the register value or select the register and press Enter/Return. You can then type in a new value.

Figure 11.28 FPU Registers window (Mac OS)

The Processes window (Figure 11.29) lists currently running processes, including some hidden processes. The Processes window also lists tasks for a selected process. To open the Processes window, choose Processes Window from the Window menu.

The Processes window has two panes and a toolbar:

• Processes window toolbar-allows you to run, stop, step through, or kill processes and tasks under the debugger's control
• Process pane-displays currently running processes
• Task pane-displays tasks in a selected process

The Processes window toolbar (Figure 11.30) has controls to attach debugging sessions to selected processes and to open the Stack Crawl window.

The Process Attach button assigns a debugging session to the selected process. This button is useful for debugging processes when the debugger cannot target those processes. For example, when debugging a program that uses dynamic link libraries or shared libraries, you can use the Process Attach button to place those libraries under the debugger's control. The Process pane displays a check mark next to attached processes.

The Stack Crawl window button displays the Stack Crawl window for the selected process or task. If a process is selected, the Stack Crawl window for that process is brought to the front. If a task is selected, the Stack Crawl window for that task is brought to the front. You can have multiple Stack Crawl windows open at a time.

The Process pane lists all active processes. A process under the debugger's control has a checkmark next to its entry in the window. To set debugger control for a process, click the checkmark column. Double-clicking a process name activates that process.

The Task pane lists all the active tasks for a given process. Only tasks from programs under the debugger's control are shown. Double-clicking a task name activates a Stack Crawl window with the code for that task. You can also choose a task and then click the Stack Crawl window button (Figure 11.30).

There are two columns in the Task pane. The first column displays the task ID. The second column shows the task's status. The task can be running, stopped, or crashed.

This section discusses how to use the debugger to locate and solve problems in your source code by controlling program execution and viewing your data and variables. The principal topics discussed are:

• Starting Up-things to watch out for when starting the debugger
• Running, Stepping, and Stopping Code-controlling program execution a line at a time
• Navigating Code-moving around and finding code
• Breakpoints-stopping execution at specific points and times
• Watchpoints-stopping execution when the contents of a memory location changes
• Viewing and Changing Data-seeing your variables and modifying them at will
• Editing Source Code-editing source code while in a debugging session

To use the debugger, first open a project. Next, choose Enable Debugger from the Project menu. Then, choose the Debug command from the Project menu to debug the project.

When using the debugger on your code, you should pay careful attention to what happens. The following two situations can occur:

• If you choose Debug from the Project menu to debug a project, the debugger displays the Stack Crawl Window. Typically, the debugger stops the program's execution at the first line of code in the main function. If you encounter this situation, all is well. Your program's code is stopped and ready to run.
• If you open a symbolics file, the debugger displays the Source Code Browser Window. In this case, you must choose Debug from the Project menu or click the Run button in the Debugger toolbar. Then, the debugger launches the build target, takes control of that build target, brings the Stack Crawl window to the front, and stops the program at the first line.

The debugger might ask you for the location of a particular file, as shown in Figure 11.33 (Windows) or Figure 11.34 (Mac OS).

You might see this dialog either upon startup (the debugger is looking for the file with the main entry point) or by clicking on a specific file in the Source Code Browser Window.

The debugger might ask you to locate files in these situations:

• a file has been moved to a different directory
• you received the project from another person on your team and the paths are different
• you selected a file belonging to a compiled library and you do not have the source files

Once you find the file, the debugger will remember the new location, even between debugging sessions.

For more information, see "Generating Symbolics Information" on page 393.

This section discusses how to how to run your code, step through it line by line, and stop or kill the build target when you want to stop debugging.

Moving through code line by line is often called "stepping" through your code. It is a linear approach to navigation, where you start at the beginning and move steadily through the code. This is important for understanding how to navigate your code. The debugger lets you navigate to any location directly, stop your code at specific locations when certain conditions are met, and view as well as modify your data.

To step through your code, you can use the debugger toolbar buttons, the keyboard, or choose the appropriate menu command. Table 11.3 lists the debugger toolbar buttons along with their Debug menu commands and their default keyboard equivalents.

Button	Menu Command	Windows Keyboard Equivalen	Mac OS Keyboard Equivalent	Solaris Keyboard Equivalent
	Run	F5	Command-R	Command-R
	Stop		Control-P	Control-P
	Kill	Shift-F5	Control-K	Control-K
	Step Over	F10	Control-S	Control-S
	Step Into	F11	Control-T	Control-T
	Step Out	Shift-F11	Control-U	Control-U

This section discusses:

• Current-statement arrow
• Running your code
• Stepping through a single line
• Stepping into routines
• Stepping out of routines
• Skipping statements
• Stopping execution
• Killing execution

The current-statement arrow in the Stack Crawl window (Figure 11.35) indicates the next statement to be executed. It represents the processor's program-counter register. When you begin a debugging session, the current-statement arrow points to the first line of executable code in your program.

If the program is running but its execution has stopped, use the Run command (Figure 11.36) to restart your program. The program resumes execution at the current-statement arrow.

After a breakpoint or a Stop command, the debugger regains control and displays the Stack Crawl window with the current-statement arrow and the current values of variables. The debugger places an implicit breakpoint at the program's main entry point and stops there (Figure 11.37). Issuing another Run command resumes program execution from the point of the interruption. After a Kill command, Run restarts the program from its beginning.

Figure 11.37 Starting the program's execution

To execute one statement, use the Step Over command (Figure 11.38). If the statement is a routine call, the entire called routine executes and the current-statement arrow proceeds to the next line of code. In other words, the Step Over command executes a routine call without visiting the code in the called routine. This behavior holds true if the routine does not have breakpoints and does not call other routines. When you step over code and reach the end of a routine, the current-statement arrow returns to the routine's caller.

Sometimes you want to follow execution into a called routine. To execute one statement at a time and follow execution into a routine call, use the Step Into command (Figure 11.39).

Step Into moves the current-statement arrow down one statement, unless the current statement contains a routine call. When Step Into reaches a routine call, the debugger follows execution into the routine being called.

To execute statements until the current routine returns to its caller, use the Step Out command (Figure 11.40). Step Out executes the rest of the current routine normally and stops the program when the routine returns to its caller. You go one level back up the calling chain. See "Call-chain navigation" on page 438 for more information.

Sometimes you may want to skip statements altogether and not execute them at all. To move the current-statement arrow to a different part of the currently executing source code, simply drag it to a new position, as shown in Figure 11.41. Note that dragging the current-statement arrow up or down does not execute the statements between the arrow's original position and its new position.

To move the current-statement arrow without potentially corrupting the run-time environment, Alt/Option click a statement in the Breakpoint column (Figure 11.42). Alt/Option clicking the statement sets a temporary breakpoint: Execution proceeds normally until the current-statement arrow reaches the temporary breakpoint, then stops. After execution stops, the temporary breakpoint is automatically removed. For more information, see "Breakpoints" on page 442.

While your program is running, you can use the Stop command (Figure 11.43) to suspend execution and explore your code with the debugger. You can then step through your code from that point, or use the Run command to resume execution.

Stopping in this manner is not very precise. Code executes very quickly, and there is no telling exactly where your program is suspended when you issue the Stop command. Instead of stopping code, you can use breakpoints, which allow you to suspend a program's execution at a specific point. To learn more, see "Breakpoints" on page 442.

Sometimes you want to terminate your program completely and end the debugging session. The Kill command (Figure 11.44) ends the program and returns control to the debugger. The Stack Crawl window tells you when the program is running, and to choose Stop from the Debug menu to stop it.

Killing the program is not the same as stopping. The Stop command only suspends execution temporarily: you can resume from the point at which you stopped. The Kill command permanently terminates the program.

This section discusses the various ways you can move around in your code. This skill is vital when you want to set breakpoints at particular locations. Methods of moving around in code include:

• Linear navigation-stepping though code
• Call-chain navigation-moving to active routines
• Source Code Browser window navigation-moving to code in the Source Code Browser window
• Changing font and color-modifying font styles and text colors to make your code easier to read

You can "walk" through your code by using the Step Over, Step Into, and Step Out commands as needed until you reach the place you want. This is useful for short stretches of code, but not very helpful when you want to get to a specific location many steps away.

"Stepping through a single line" on page 433, "Stepping into routines" on page 434, and "Stepping out of routines" on page 434 describe various ways to linearly navigate through your code.

The chain of routine calls is displayed in the Stack Crawl pane of the Stack Crawl window (Figure 11.45). Each routine in the chain is displayed below its caller, so the currently executing routine is at the bottom of the chain and the first routine to execute in the program is at the top.

You can use the Stack Crawl pane to navigate to the routines that called the halted routine. To find the point where a routine in the Stack Crawl pane is called, click the name of the routine's caller. The source code for the caller is displayed in the Source pane, right at the point of the call (Figure 11.46).

You can use the Source Code Browser window to jump to any location in your source code. The debugger displays this window only when you open a symbolics file. To view a specific routine, follow these steps:

1. Make the Source Code Browser window active (Figure 11.47).

2. In the Source Code Browser window's Files pane, select the file where the routine is defined (Figure 11.48).

Simply click the desired file, or use the arrow keys to scroll through the list. The source code for that file appears in the Source pane. You can also type the name of the file.

3. Locate the desired code in the source file.

Scroll through the Source pane to find the code you want. A more useful technique is to use the Source Code Browser window's Functions pane or Function pop-up menu to select the desired routine (Figure 11.49). The routine is displayed in the Source pane, allowing you to set and clear breakpoints. For more information, see "Breakpoints" on page 442.

The debugger displays source code in the font and color specified in the Editor preference panels of the IDE Preferences window.

For more information, see "Editor Preferences" on page 268.

A breakpoint suspends execution of a program and returns control to the debugger. When the debugger reaches a statement with a breakpoint, it stops the program before the statement is about to execute. The debugger then displays the routine containing the breakpoint in the Stack Crawl window. The current-statement arrow moves to the line containing the breakpoint and points to the next statement that is ready to execute.

This section discusses:

• Setting and clearing breakpoints
• Temporary breakpoints
• Viewing breakpoints
• Conditional breakpoints
• Setting breakpoints for templated or redefined functions
• Impact of optimizing code on breakpoints

From the Source pane of the editor window, Stack Crawl window, or Source Code Browser window, you can set a breakpoint on any line with a dash marker-the short line to the left of a statement in the Breakpoint column (see Figure 11.50). The dash becomes a dot (on color monitors, the default dot color is red). This dot indicates that a breakpoint has been set at this statement. Execution will stop just before this statement is executed.

Figure 11.50 Setting breakpoints

Another way to set a breakpoint is to click a particular line of source code in the Stack Crawl window and choose Set Breakpoint from the Debug menu.

To clear a single breakpoint, click the breakpoint dot in the Source pane. The dot turns back into a dash, indicating that you have removed that breakpoint.

You can manipulate breakpoints with the following commands in the Debug menu:

• Clear Breakpoint-removes the breakpoint from the current line
• Enable Breakpoint-makes the breakpoint on the current line active
• Disable Breakpoint-makes the breakpoint on the current line inactive
• Clear All Breakpoints-removes all breakpoints from the current program
• Show Breakpoints-displays the Breakpoint column when it is currently hidden
• Hide Breakpoints-removes the Breakpoint column when it is currently visible

Regular breakpoints stop a program's execution each time you debug your project. However, you can also set temporary breakpoints that stop a program's execution only once. When the temporary breakpoint is reached, the debugger stops the program and then removes the temporary breakpoint.

To set a temporary breakpoint, Alt/Option click the breakpoint dash to the left of the desired statement.

If the debugger encounters another breakpoint before reaching the temporary breakpoint, the program stops at the first breakpoint. The temporary breakpoint remains in place. After the temporary breakpoint is reached, it is triggered and then removed.

To see a list of all active breakpoints in your program, choose the Breakpoints Window command from the Window menu. The debugger displays a window that lists the source file and line number for each breakpoint (Figure 11.51). Clicking a breakpoint marker in the Breakpoints window toggles the breakpoint's status between active and inactive. A dot indicates that the breakpoint is active. The debugger stops the program's execution upon reaching an active breakpoint. A circle indicates that the breakpoint is inactive. The debugger continues to execute the program without stopping at an inactive breakpoint. The debugger remembers the position of inactive breakpoints in the program.

For more information, see "Breakpoints Window" on page 413.

You can set conditional breakpoints that stop your program's execution at a given point only when a specified condition is met. A conditional breakpoint is an ordinary breakpoint with a conditional expression attached. If the expression evaluates to a true (nonzero) value when control reaches the breakpoint, the program's execution stops; if the value of the expression is false (zero), the breakpoint has no effect and program execution continues.

Conditional breakpoints are created in the Breakpoints window. To specify a conditional breakpoint:

1. Set a breakpoint at the desired statement.

2. Display the Breakpoints window by choosing Breakpoints Window from the Window menu.

3. In the Breakpoints window, double-click the breakpoint's Condition field and enter an expression, or drag an expression from a source-code view or from the Expressions window.

In Figure 11.52, the debugger stops execution at line 162 in the NewBall() routine if and only if the variable newTop is greater than six.

You can set breakpoints for templated functions as well as functions that have been redefined.

For example, suppose you have a file named file.h that defines a function void FOO(args), where FOO is a macro. If you create the lines of code shown in Listing 11.1, a pop-up menu appears in the Breakpoints column during the debugging session. This pop-up menu lets you choose whether to set a breakpoint for function1 or function2.

#define FOO function1

#include file.h

#define FOO function2

#include file.h

In order to accurately set breakpoints, the debugger relies on a direct correspondence between source code and object code. Optimizing your code can disrupt this relationship and cause problems when setting breakpoints.

If there is no breakpoint dash to the left of a line of source code, you cannot set a breakpoint at that line. The potential causes are:

• Symbolics information was disabled for that line.
• The routine containing the line was unused and was therefore deadstripped by the linker.
• The code has been optimized and the final object code no longer corresponds to the original source code.

Normally, when debugging information is enabled for a source file, the compiler tries to start a new statement block at each source statement that actually generates some code. For example, consider the source code in Listing 11.2:

	-	int i = 1;

	-	if (i)
			{									//This is the third line.
				int k;
	-			int j = 1;
	-			i = j;
			}

Since the third line does not generate instructions, it does not have a unique object code address. Therefore, the debugger does not permit a breakpoint on that line.

After you start optimizing the code, the situation changes. For example, when you enable Instruction Scheduling in the project's Global Optimizations preference panel, the compiler no longer starts a new basic block for each source statement. The scheduler gains the maximum flexibility for reordering instructions within the block. The different instructions that correspond to a source statement are no longer consecutive. Instead, they are intermingled with the instructions from other source statements. Because of these optimizations, the debugger no longer displays breakpoint dashes as shown in Listing 11.2.

When you enable additional optimizations, the source statements may not even appear in the generated code. For example, consider the following code:

		i = 0;

		j = 0;
		while (i < 10)
		{
				 	 j = j + 1;
				 	 i = i + 1;
		}

With minimal optimization, the compiler translates the code from Listing 11.3 into the following equivalent code:

	j = j + 1;        // duplicate 10 times

	j = j + 1;
	.
	.
	.
	j = j + 1;

With even more optimization, the compiler totally eliminates instructions corresponding to the while loop and uses the following equivalent code:

j = 10;

While debugging your code, you should disable optimizations or use optimizations that are "debug safe." Different optimizations are available for different build targets. See the appropriate Targeting manual for additional details, as described in "Targeting Documentation" on page 27.

You can view the current optimizations for your project in the Global Optimizations preference panel of the Target Settings window. For more information, refer to "Configuring Target Options" on page 315.

After setting a breakpoint, you can continue debugging the program. Refer to "Running, Stepping, and Stopping Code" on page 430 for additional details.

A watchpoint is a location or region of memory that you want the debugger to observe for you. Whenever a new value is written to that area of memory, the debugger suspends execution of the program and notifies you with an alert message on your screen (Figure 11.53). After dismissing the alert, you can examine the call chain, inspect or change variables, step through your code, or use any of the debugger's other facilities. (In particular, from the debugger level, you can change the contents of the location that triggered the watchpoint without triggering it again.) Use the Run command (or the Run button on the debugger toolbar) to continue execution from the watchpoint.

The following sections discuss watchpoints in more detail:

• Setting and clearing watchpoints
• Viewing watchpoints

(Mac OS) Watchpoints require System 7.5 or later, and will not work on 68K computers unless you enable virtual memory. Watchpoints are also known to be incompatible with the Speed Emulator portion of Speed Doubler, and possibly with RAM Doubler as well.

If you have a small program with a small set of global variables for 68K, the global data area is placed against the end of the stack. Since the debugger cannot detect watchpoints for variables on the stack, the global variables cannot be watched. One way to avoid this problem is to declare a global array of type char, about four kilobytes in size, to move the global variables away from the stack.

You can set a watchpoint in any of the following ways:

• Select a variable, in a Variable window or in the Source Code Browser window, and choose Set Watchpoint from the Debug menu.
• Drag a variable from another window into the Watchpoints window.
• Select a range of bytes in a Memory window and choose Set Watchpoint from the Debug menu.
• Invoke the debugger contextual menu (Figure 11.16 on page 411) for an appropriate variable or memory range and choose the Set Watchpoint command.

There are some significant restrictions on where in memory you can place a watchpoint. You can use watchpoints only on global variables or on objects allocated from your application heap. You cannot set a watchpoint on a stack-based local variable or on a variable being held in a register

You cannot set a watchpoint anywhere in low memory or the system heap. If you attempt to set a watchpoint in this area of memory, an alert box displays with the following text: "Could not set a watchpoint because the page containing that memory location overlaps low memory or the system heap."

You can clear a watchpoint in any of the following ways:

• After triggering the watchpoint, choose the Clear Watchpoint command from the Debug menu.
• Select a variable, in a Variable window or in the Source Code Browser window, and choose Clear Watchpoint from the Debug menu.
• Select a range of bytes in a Memory window and choose Clear Watchpoint from the Debug menu.
• Select an existing watchpoint in the Watchpoints window and

¯ Choose Clear from the Edit menu

¯ Press the Backspace/Delete key

All watchpoints are automatically cleared when the program's execution terminates or is killed by the debugger.

To see a list of all watchpoints currently set in your program, choose the Watchpoints Window command from the Window menu. The debugger displays the Watchpoints window (Figure 11.54).

For more information, see "Watchpoints Window" on page 414.

A critical feature of a debugger is the ability to see the current values of variables, and to change those values when necessary. This ability allows you to understand the details of your program's execution, and to experiment with new possibilities.

This section discusses the following topics:

• Viewing local variables
• Viewing global variables
• Placing data in a new window
• Viewing data types
• Viewing data in a different format
• Viewing data as different types
• Changing the value of a variable
• Using the Expressions window
• Viewing raw memory
• Viewing memory at an address
• Viewing Processor Registers

Local variables are displayed in the Variables pane of the Stack Crawl window (Figure 11.55). If the variable is a handle, pointer, or structure, you can click the hierarchical control to the left of the name to expand the view. This allows you to see the members of the structure, or the data referenced by the pointer or handle.

To learn some useful tips for using hierarchical controls, see "Expanding and Collapsing Groups" on page 74. For more information about the Variables pane of the Stack Crawl window, refer to "Variables pane" on page 398.

To view global variables, choose Global Variables Window from the Window menu. Next, click the Global Variables item in the File pane (Figure 11.56). Then, the Variables pane displays the global variables in your program.

For more information, refer to "Global Variables Window" on page 412.

Sometimes the Variables pane and Global Variables window are not the most convenient places to view data. You can place any variable or group of variables in a separate window.

To place a variable or memory location in its own window, double-click its name (Figure 11.57) or select the name and choose the View Variable command from the Data menu or the debugger contextual menu (Figure 11.16 on page 411). If the variable is an array, use the View Array command instead. To view the memory the variable occupies as a memory dump, use either the View Memory or View Memory As command.

For more information, see "Variable Window" on page 416, "Array Window" on page 417, and "Memory Window" on page 418.

If you wish, the debugger can display the data types of variables on a window-by-window basis. Select the window or pane in which you want data types displayed and choose Show Types from the Data menu or the debugger contextual menu (Figure 11.16 on page 411). Then, the names of the variables and memory locations in that window or pane are followed by the relevant data type (Figure 11.58).

To show data types automatically, enable the following preference in the Display Settings preference panel of the IDE Preferences window:

In variable panes, show variable types by default

See "Display Settings" on page 279 for more information.

You display a variable's value in several formats:

• signed decimal
• unsigned decimal
• hexadecimal
• character
• C string
• Pascal string
• floating point
• enumeration
• Fixed
• Fract

Not all formats are avialable for all data types. For example, if a variable is an integral value (such as type short or long), you can view it in signed decimal, unsigned decimal, hexadecimal, character, or string format. However, you cannot view the same variable in floating-point, Fixed, or Fract format.

The View As command in the Data menu lets you change the data type in which a variable, register, or memory value is displayed:

1. Select the item in a window or pane.

2. Choose View As from the Data menu.

Alternatively, you can use the debugger contextual menu (Figure 11.16 on page 411) to select the same command. After you select View As, the debugger displays the View As dialog box, shown in Figure 11.60.

3. Select the data type by which to view the item.

The data type you select is displayed in the New Type text field near the bottom of the dialog box. If you want to treat the item as a pointer, append an asterisk (*) to the type name.

4. Click OK.

The display of the item's value changes to the specified type.

You can change the value of a variable in any variable view. Variables are displayed in several debugging windows: the Variables pane of the Stack Crawl window or Source Code Browser window, a Variable window, an Array window, or the Expressions window. To change the value, double-click the variable (or select it and press Enter/Return) and type the new value (Figure 11.61).

You can enter variable values in any of the following formats:

• decimal
• hexadecimal
• floating point
• C string
• Pascal string
• character constant

The Expressions window provides a single place to put frequently used local variables, global variables, structure members, array elements, and complex expressions without opening and manipulating several windows. To open this window, choose Expressions Window from the Window menu. You can add an item to the Expressions window by dragging and dropping that item from another window, or by selecting the item and choosing Copy to Expression from the Data menu or the debugger contextual menu (Figure 11.16 on page 411).

The contents of the Expressions window are updated whenever execution stops in the debugger. Any variable that is out of scope is left blank. You can take advantage of the Expressions window to perform a number of useful tasks:

• Move a routine's local variables to the Expressions window before expanding them to observe their contents. When the routine exits, its variables remain in the Expressions window and are still expanded when execution returns to the routine. The Expressions window does not automatically collapse local variables when execution leaves a routine, like the Variables pane in the Stack Crawl window.
• Keep multiple copies of the same item displayed as different data types, by using the Copy to Expression and View As commands in the Data menu and the debugger contextual menu.
• Keep a sorted list of items. You can reorder items by dragging them within the Expressions window.
• View local variables from calling routines. You don't have to navigate back up the calling chain to display a caller's local variables (which hides the local variables of the currently executing routine). Add the caller's local variables to the Expressions window to view them without changing levels in the Stack Crawl pane.

To examine and change the raw contents of memory:

1. Select an item or expression representing the base address of the memory you want to examine.

2. Choose View Memory from the Data menu.

A new Memory window opens, displaying the contents of memory in hexadecimal and ASCII format. You can change memory directly from the Memory window by entering hexadecimal values or characters. You can also change the beginning address of the memory being displayed by changing the expression in the Display text field at the top of the window.

The View Memory and View Memory As commands in the Data menu allow you to follow any pointer-including an address stored in a register-and view the memory to which it currently points. To display the memory referenced by a pointer:

1. Select the value of the variable or register in a window in which it is displayed.

2. Choose View Memory or View Memory As from the Data menu.

If you choose View Memory, a Memory window opens displaying a raw memory dump starting at the address referenced by the pointer. If you choose View Memory As, a dialog box opens and asks you to select a data type (Figure 11.62); continue with step 3.

3. If you chose View Memory As, select a data type in the View As dialog box.

The data type you select is displayed in the New Type text field near the bottom of the dialog box. To view the memory pointed to by a register, append an asterisk (*) to the type name.

4. Click OK.

A new window opens (Figure 11.63) and displays the contents of memory, starting at the address referenced by the pointer.

For more information, refer to "Memory Window" on page 418.

To view the contents of the processor's general registers, choose Window > Registers Windows > General Registers from the Window menu (Figure 11.64).

For more information, see "Register Windows" on page 421.

You cannot edit source code directly in the debugger. However, you can use the debugger to open the source-code file so that you can modify your code. In the Files pane of the Source Code Browser window, you can double-click a file name to open the file in an editor window.

You can specify that a third-party editor open the file. See "IDE Extras" on page 254 for more information.

An expression represents a computation that produces a value, and the debugger displays the value in the Expressions window. You can attach an expression's value to breakpoints and watchpoints. The debugger evaluates all expressions each time it executes a statement.

An expression can combine literal values (numbers and character strings), variables, registers, pointers, and C++ object members with operations such as addition, subtraction, logical and, and equality.

An expression can appear in the Expressions window, the Breakpoints window, or a Memory window. The debugger treats the result of the expression differently, depending on the window in which the expression is displayed.

This section discusses how expressions are treated and used in the debugger. The topics in this section are:

• How Expressions are Interpreted
• Using Expressions
• Example Expressions
• Expression Syntax

The debugger interprets expressions in various ways, depending on their locations:

• Expressions in the Expressions Window
• Expressions in the Breakpoints Window
• Expressions in a Memory Window

The Expressions window displays expressions and their values. To see the value of an expression, place it in the Expressions window. To create a new expression:

1. Choose Expressions Window from the Window menu.

If the Expressions window is already open, click it to make it active.

2. Choose New Expression from the Data menu.

3. Type a new expression and press Enter/Return.

The expression's value is displayed in the Value column next to that expression (Figure 11.65). You can also create a new expression by dragging a variable or expression from another window to the Expressions window.

The Expressions window treats all expressions arithmetically: the debugger does not interpret the expression's result as a logical value, as it does in the Breakpoints window.

For more information, see "Expressions Window" on page 411.

You can attach an expression to a breakpoint in the Breakpoints window. The Breakpoints window treats expressions logically rather than arithmetically.

If the expression yields a false (zero) result, the debugger ignores the breakpoint and continues execution. If the result is true (nonzero), the debugger stops at the breakpoint if the breakpoint is active. To learn how to set a breakpoint, see "Setting and clearing breakpoints" on page 443.

You can attach an expression to a breakpoint to make the breakpoint conditional on that expression:

1. Choose Breakpoints Window from the Window menu.

If the Breakpoints window is already open, click it to make it active.

2. Set a condition.

Double-click the condition field for the desired breakpoint and type an expression (Figure 11.66). You can also add or change a breakpoint's condition by dragging an expression from another window and dropping it on the breakpoint's condition.

A conditional breakpoint stops the program if the expression yields a true (nonzero) result when execution reaches the breakpoint. If the expression produces a false (zero) result, execution continues without stopping.

For more information, refer to "Breakpoints Window" on page 413 and "Conditional breakpoints" on page 446.

In a Memory window, expressions are treated as addresses. The expression in the Display text field at the top of the window defines the base address for the memory displayed in the window. To change a Memory window's base address, follow these steps:

1. Choose View Memory from the Data menu.

If a Memory window is already open, click it to make it active.

2. Enter a new expression.

Double-click the Display field and type an expression. You can also drag an expression from another window and drop it in the Memory window's Display field.

The Memory window displays the contents of memory beginning at the address obtained by evaluating the new expression.

Refer to "Memory Window" on page 418 for more information.

The debugger's expression syntax is similar to that of C/C++, with a few additions and limitations. Pascal style expressions are also supported. The topics discussed include:

• Special Expression Features
• Expression Limitations

Expressions can refer to specific items:

• The debugger considers integer values to be 4 bytes long. Use the short data type to denote a 2-byte integer value.
• The debugger treats double values as objects 10 bytes (80 bits) in length, rather than 8 bytes (64 bits).
• To compare character strings, use the == (equal) and != (not equal) operators. Note that the debugger distinguishes between Pascal- and C-format strings. Use the prefix \p when comparing Pascal string literals. The expression

  "Nov shmoz ka pop" == "\pNov shmoz ka pop"

Expressions have the following limitations:

• Do not use C/C++ preprocessor definitions and macros (defined with the #define directive). They are not available to the expression evaluator, even though they are defined in the source code.
• Do not use operations involving side effects. The increment (i++) and decrement (i--) operators, as well as assignments (i = j), are not allowed.
• Do not call functions.
• Do not use function names or pointers to functions.
• Do not use expression lists.
• Do not use pointers to C++ class members.
• The debugger cannot distinguish between identical variable names used in nested blocks to represent different variables (see Listing 11.4).

// The debugger cannot distinguish between x the

// int variable and x the double variable. If x is

// used in an expression, the debugger will not

// know which one to use.

void f(void)

	{

		int x = 0;

		.

		.

		.

		{

			double x = 1.0;

			.

			.

			.

		}

	}

• Type definitions that are not available to the debugger cannot be used in expressions (see Listing 11.5).

// Use long in expressions; Int32 not available

typedef long Int32;

// Use Rect* in expressions; RectPtr not available

typedef Rect* RectPtr;

• Nested type information is not available. In Listing 11.6, use Inner, not Outer::Inner in a debugger expression.

// To refer to the i member, use Inner.i,

// not Outer::Inner.i

struct Outer

	{

		struct Inner

			{

				int i;

			};

	};

The list below provides example expressions that you can use in any window that uses expressions.

• A literal decimal value:
   160

• A literal hexadecimal value:
   0xA0

• The value of a variable:
   myVariable

• The value of a variable shifted 4 bits to the left:
   myVariable << 4

• The difference of two variables:
   myRect.bottom - myRect.top

• The maximum of two variables:
   (foo > bar) ? foo : bar

• The value of the item pointed to by a pointer variable:
   *MyTablePtr

• The size of a data structure (determined at compile time):
   sizeof(myRect)

• The value of a member variable in a structure pointed to by a variable:
   myRectPtr->bottom

Below are examples of logical expressions: the result is considered true if non-zero, false if zero.

or

or

This section defines the debugger's expression syntax. Each listing follows several conventions to make it easier to read:

• The first line in a definition identifies the item being defined.
• Each indented line represents a definition for that item.
• An item with more than one definition has each definition listed on a new line.
• Items enclosed in angle brackets (<>) are defined elsewhere.
• Items in italic typeface are to be replaced by a value or symbol.
• All other items are literals to be used exactly as they appear.

defines the syntax of a name. A name can be either an identifier or a qualified name; the latter is a syntactic category described in another of the definitions listed in this section.

The following list describes expression syntax:

This section discusses various problems people have encountered while debugging their programs. There are suggested solutions for each problem.

The general topics include:

• General Problems
• Problems Launching the Debugger
• Problems Running/Crashing the Debugger
• Problems with Breakpoints
• Problems with Variables
• Problems with Source Files

There may come a time when one of the solutions in this section does not seem to work, or your specific problem is not discussed. The following list details additional steps you can take to try resolving the problem:

• Remove easily regenerated files and data, including .(x)sym files, .dbg files, preferences, binaries in your project (by choosing Remove Object Code from the Project menu. See "Removing Object Code" on page 363 for more information).
• Copy the newest version of the IDE to your hard drive.
• (Mac OS) Check for extension conflicts.
• (Mac OS) Try a few sample sessions with all possible extensions disabled.

This section lists questions and problems with launching the debugger.

Even if Enable Debugger is selected from the Project menu, when I debug my application the debugger does not launch.

The Run or Debug command in the CodeWarrior Project menu is dimmed.

You can launch the debugger automatically from the CodeWarrior IDE only if the project is an application project, the debugger is enabled, and the project is properly configured to generate debugging information.

• Make sure your project generates an application. The Run command is only available when creating an application.
• Make sure that the debugger is enabled. Choose Enable Debugger command from the Project menu to enable the debugger. If you see the Disable Debugger command instead, the debugger is already enabled.
• Set up your project to generate symbolics information for the debugger. For more information, see "Preparing for Debugging" on page 390.

The Debug command does nothing.

You must have everything configured properly for the debugger to work correctly. In addition, make sure your code actually does something!

• Make sure debugging is enabled for the project. See "Preparing for Debugging" on page 390 for more information.
• Consult the IDE release notes for the latest information on incompatibilities with third-party software.

I get error -27 when I start debugging and -619 when I quit.

You may be using an older version of Ram Doubler that is not compatible with the debugger.

• Upgrade Ram Doubler to version 1.5.2 or later.

This section covers problems that occur while you are running the debugger.

My project works fine when running under the debugger's control. When I run the project without the debugger, my program crashes.

Running a program under the debugger changes the operating environment in which the program runs. This can have the strange effect of making an otherwise flawed program work correctly. It is difficult to pinpoint the cause of this problem in your code, but there are two likely factors that can cause the odd behavior.

• The debugger slows down the program's execution. If you have code that is time-sensitive, things may happen too quickly when the debugger is not present. Keep this in mind when studying the problem.
• The presence of the debugger can also modify memory management of the project. A block of memory cannot move if the debugger is running, for example. With the debugger absent, the block moves and a memory-related bug results.

• Look for time-sensitive problems, race conditions, and similar factors in your code.
• Look for memory-related problems, such as accessing null pointers or handles, improperly disposing of resource handles, or disposing of handles more than once.

This section covers problems related to setting and clearing breakpoints.

Some statements don't have dashes in the Breakpoint column, making it impossible to set them.

The CodeWarrior linkers do not generate symbolics information for source code that is not linked into the final output file. If a statement is never actually used, the linker does not include it in the final object code. You cannot set a breakpoint on such a statement, because the object code does not exist.

Code optimization may also reorganize the object code extensively, affecting the correspondence between object code and source code and making it difficult or impossible to set breakpoints accurately.

• Make sure all your code is used. Change the source code if necessary.
• Check your source code to see if statements were ignored by the compiler because of compiler directives.
• Disable all compiler optimizations and rebuild your project. Optimization may make changes in object code that do not correspond to your source code. You should get a breakpoint marker at every available statement after disabling optimizations. For more information, see "Impact of optimizing code on breakpoints" on page 448.
• Use a coding style wherein you place only one statement on a source line. The compiler outputs breakpoint information for multiple statements on a line, but the debugger only displays the current source line. You might step multiple times on the same source line.

I set a breakpoint, but it does not work.

A breakpoint stops execution only if it is reached, it is active, and its condition (if it has one) is true.

• Step through your code to verify whether you reach the statement at which you placed the breakpoint. To learn more, refer to "Setting and clearing breakpoints" on page 443.
• Look in the Breakpoints window to see if the breakpoint is inactive.
• If the breakpoint has a condition, make sure it evaluates to true. The debugger ignores breakpoints with false conditions. See "Conditional breakpoints" on page 446 for more information.

This section covers problems related to variables.

I have a variable and I assign it a value, but the value does not change in the debugger.

You are not using the variable in the code. As a result, the compiler optimizes the final output file so that the variable is not used.

• Remove the unused variable from your code.
• Modify your code to use the variable.

I notice that values seem to be changing incorrectly. I encounter one of these two problems:

• Two or more variables are set to the same value simultaneously.
• One variable receives a value that is supposed to be assigned to another.

The compiler has recognized that the variables are not used concurrently, and has given the variables the same storage location. What you are seeing is a kind of automatic compiler optimization called "register coloring." Register coloring checks to see how variables are used in a routine. If two or more variables are in the same scope but are not used at the same time, the compiler may use the same processor register for both variables. Using registers instead of memory to store and manipulate variables improves a program's performance.

Listing 11.7 is a good example of the kind of code that results in register coloring. Because four different variables are set but never used simultaneously, the compiler has arranged for all four to use the same register. The debugger, however, has no way of knowing that all four variables share the same register, so it shows all four variables changing with each assignment.

void main(void)

{

	long a = 0, b = 0, c = 0, d = 0;

	a = 1; /* a is set to 1 */

	a = 2; /* a is set to 2, b remains unchanged */

	a = 3; /* a is set to 3, c remains unchanged */

	a = 4; /* a is set to 4, d remains unchanged */

}

• Do nothing. Register coloring is not a problem.
• To prevent register coloring in C/C++, declare your variables with the volatile keyword. Do this with a preprocessor directive so that you can easily remove the volatile storage class specifiers after debugging. See the C Compilers Reference and the Assembler Guide for more information.

The debugger shows variables in the Variables pane or Global Variables window that are not declared in the source code.

The compiler often creates its own temporary variables in the object code as it translates source code. These temporary variables have a dollar sign ($) in their names. The debugger also displays C++ virtual base class types with a $ prefix.

The compiler and linker often add variables from libraries and run-time routines that help initialize and terminate your program.

• None. This is not a problem that needs correction.

When I select Show Types from the Data menu, some enumerated values are displayed as having type "?anonx," where x is an arbitrary number.

The debugger cannot display the names of enumerated types if the names are not defined in the source code. At compile time, the compiler assigns a generic type name to such enumerated types. It is this generic name that the debugger displays.

For example, in Listing 11.8, with Show Types selected, variable myMarx is displayed as having the anonymous type ?anonx, because its enumerated type has no name. On the other hand, variable myBeatle is shown with type Beatle, because its enumerated type is defined with that name.

// Debugger displays as anonymous type

enum {Groucho,

			Harpo,

			Chico,

			Zeppo } myMarx = Harpo;

// Debugger displays as type Beatle

typedef enum Beatle {John,

										Paul,

										George,

										Ringo} myBeatle = John;

• None. This is not a problem that needs correction.

I declared my own data type. Why can I not view a variable as that type?

The symbolics file includes information only about types that are used in the program. Types defined in typedef statements are not stored in the symbolics file, so you need to view the variable as the type from which it is derived. For example, if you declare a type MyLong based on the long data type, you can view it as a long, but not as a MyLong. For more information, refer to "Viewing data as different types" on page 458.

• Use the base data type.
• Choose the Show Types item from the Data menu to see how the debugger labels the type.

A user-defined type in an expression in the Expressions window gives an "· undefined identifier ·" value.

The debugger does not recognize data types that are simply aliases of another type, because such alias types are not included in the symbolics file.

For example, given the Pascal type declaration

the expression

in the debugger's Expressions window will display its value as "· undefined identifier ·." To get the correct result, use the following expression instead:

To learn more, see "Expression Limitations" on page 469.

• Use the original data type instead of the defined data type.

This section covers problems related to source-code files.

All I see in the source pane is assembly-language code. The Source pop-up menu does not let me display source code.

There is no symbolics information available for that code. You may not have enabled debugging for a file, or you may be stepping through some ancillary code added by the linker that has no corresponding source code (for example, glue code). Without symbolics information, the debugger can only display the code in assembly language.

• If the code is from your own source file, make sure to generate symbolics information for the file. For more information, refer to "Setting Up a File for Debugging" on page 392.
• If the code is from some other source (such as a compiled library), step out of the function to return to the caller. There is no source code to view.

When I run my project, I get a warning that says the modification dates do not match.

The symbolics file keeps track of when the source file on which it is based was last changed. If the date and time stored in the symbolics file do not match those of the original file, the debugger warns you that the symbolics information may no longer be current.

• Touch the source file (or make a do-nothing change and save the file), then rebuild your project or bring it up to date.

I am working on a Pascal program, and when I step through code I find ANSI C routines. I have not included any ANSI C libraries.

The Pascal runtime library was written in C and uses ANSI C routines. These are the routines that are displayed when debugging a Pascal program.

• None. This is not a problem that needs correction.

The following is a list of error messages that you may receive from the debugger, with some hints about the possible causes or circumstances of the error. Messages listed without comment are self-explanatory.

Internal error.

Attempt to read or write to an invalid address.

The symbolics file contains a data type that the debugger does not support.

The debugger does not have access to the same text available to the compiler. The debugger just issues a warning unless the debugging information references nonexistent text, in which case it gives you this error message.

Unexpectedly encountered something other than a class name while evaluating an expression.

The command you issued cannot be performed while the program is running.

Watchpoints cannot be set in low memory or in the system heap.

Watchpoints are implemented via the memory write-protection mechanism, which operates at the page level. You cannot write-protect a page of memory containing part of the stack.

When launching a program, the debugger normally sets an implicit breakpoint at the beginning of the function named main() (in C/C++) or the main program (in Pascal). If the debugger cannot find such a routine, it just launches the program without suspending that program's execution.

Unexpectedly encountered something other than an indentifier or qualified name while evaluating an expression.

Invalid character constant encountered while evaluating an expression.

Invalid string constant encountered while evaluating an expression.

Invalid token encountered while evaluating an expression.

An ill-formed string was encountered in evaluating an expression.

An invalid character constant was encountered in evaluating an expression.

C/C++ escape sequence in a string was not valid syntax.

Invalid pointer or reference expression encountered while evaluating an expression.

Invalid type encountered while evaluating an expression.

The debugger is unable to display a variable because of bad data in the symbolics file.

For example, you have attempted to assign a 20-byte string to a 10-byte string variable.

The debugger does not recognize a type name you have entered in the View As dialog box.

The debugger is unable to get a valid register value to display a register variable. For example, when looking at routines up the stack from the current routine, the debugger cannot retrieve the saved register values unless all routines below it on the stack have debugging information.

String exceeds maximum permissible length.

You have attempted to assign a value of the wrong type to a variable, such as a string to an integer variable.

Unexpectedly encountered something other than a typedef name while evaluating an expression.

The debugger cannot step execution from this point.

The debugger cannot step out from this point.

Undefined identifier encountered while evaluating an expression.

Unexpected token encountered while evaluating an expression.

An internal error that was not expected to reach the user.

A closing comment bracket is missing.

For example, if r is a Rect, *(char*)r is invalid.

Your symbolics file may have been corrupted.

Unexpectedly encountered something other than a pointer or reference operator while evaluating an expression.